home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ShareWare OnLine 2
/
ShareWare OnLine Volume 2 (CMS Software)(1993).iso
/
database
/
msgobj10.zip
/
MSGOBJ.DOC
< prev
next >
Wrap
Text File
|
1993-03-26
|
11KB
|
239 lines
MessageObject 1.0 for Pip message base
by R.Piola, 1993 (wow! it's the first program I release in '93)
These sources provide an easy way to access messages stored in PIP format.
Future development includes also an interface to Fido *.MSG and Hudson
QuickMessageBase.
They're written in Borland C++ 2.00, and I hope that they will work on most
C++ compilers.
SMALLPIP and SMALLPOS are a little message reader and a little message poster
(i.e.: a program that puts a file into a message) to demonstrate how to use
MessageObject. Please notice that they use configuration files created by
PipBase, or Gimme-A-Point, or PipSetup, or Pip* 2.00, and you have to get one
of these packets in order to have a message base where you can work on.
Signal every bug or everything I forgot to: Roberto Piola, fidonet
2:334/108.57 (or 2:334/306.666), via netmail or via PIPBASE.334 and NET_DEV
conferences ,or via slow mail (via Roasio 6, 10143 Torino (TO), Italy), or
by phone: +39-11-7496686 (monday to friday) or +39-121-500663 (on weekends).
MODULES CONTAINED IN THIS ARCHIVE:
AREAS.CPP To handle BaseDesc.Pip area configuration file
AREAS.H ' '
CONFIG.H MsgObj configuration values (it's only an example!)
MSGOBJ.H Main include file and area definition
MSGOBJ.CPP Private functions
MSGOBJAD.CPP Methods to parse and store addresses
MSGOBJDT.CPP Methods to parse and process dates
MSGOBJMS.CPP Methods to process messages
MSGOBJPI.CPP Methods to compress and uncompress messages in Pip format
MSGOBJ.DOC This text
MSGOBJ.MAK A simple makefile
PIPBASE.H PipBase structure definitions
PIPEXT.H Some variables where Pip* loads configuration datas; they're
used by our examples
SMALLPIP.CPP A little message reader (example)
SMALLPOS.CPP A little program to send a message (example)
MESSAGEOBJECT BASICS
MessageObject can access messages in Pip message bases (and in future also in
other message bases) in an easy way.
Every area is identified by a number (form 0 to 32767).
Every message in every area is identified by a number, starting form 0.
MessageObject allows you to read a message (or only its header), insert a
message into the message base, modify it and delete it, plus some other
utilities (like finding the last origin line and extracting path and seen-byes
from echomail messages).
HOW CAN YOU INCORPORATE MSGOBJ IN YOUR PROGRAMS?
The first thing you have to do is modifying CONFIG.H file and define how
MessageObject will interface himself with your configuration files.
In particular, you should define (if you don't define them, MsgObj will assume
that Pip* configuration files are used):
TEARLINE a char* to your tear line (without initial ---)
AREATYPE(a) the type of the area number a: an integer; currently MsgObj
supports only areas of type 0 (Pip)
AREAPATH(a) the path to your message base, backslash terminated; for Pip
base it is a constant
AREATAG(a) char* to the echomail tag of area number a, or to the special
string "#NETMAIL" for netmail area, "#BAD" for bad messages
area, "#DUPES" for dupes area and "#LOCAL" for local non-echo
areas (i.e.: areas without a tag)
MYZONE
MYNET
MYNODE
MYPOINT four unsigned integers and a char* identifying your network
MYDOMAIN address (in fidonet-technology-based networks)
MYFAKENET your fakenet, if you use it, or 0 for 4-D addressing
BUFSIZE the size (in bytes) of the buffer for the message text;
in most operations, MsgObj will process only messages that will
fit in this buffer, truncating them if they will exceed this
limit, so keep this number rather large (but remind that some
diffuse software cannot handle message longer than 16K, and
most string functions are limited to 64K strings; I use 30000
bytes, and this is the default)
(see also MSGOBJ.H to see default values for these definitions).
Second: you have to instantiate an object of the class message_frame: this
object (I'll call it MsgFrame) will be a window on your message base.
Third: use this object; to use it you'll have to place your datas in
MsgFrame's fields and then call the appropriate MsgFrame function. Functions
and fields are explained in nect section.
Fourth, IMPORTANT: when you exit your program, remember that you'll have to
call MsgFrame destructor, or Message Object will leave your files open; it
may destroy part of your message base! Never use abort and, under MS Windows,
intercept WM_PREPARETOQUIT messages.
Most functions reports -1 when they fail, and the ser MsgFrame.lasterror to a
code; see the table at the end of MSGOBJ.H to interpretate this code.
For every doubt, see examples, and then write me.
MSGOBJ FUNCTIONS AND FIELDS
We will consider only the last class defined in MSGOBJ.H; other classes are
rather simple, and are left to your analisys :-) until I'll have anought
free time to document them.
Private members are not of interest.
lasterror: an integer containg an error code form the last operation, or
MSGERR_NOERR if no error has occurred.
pipstring,unpipstring,unpipfile,read0,reafile,write0 and writemex: all these
functions are used internally; I've placed them in the public
section only because I use them in my programs and I didn't want
to duplicate them. You're free to see them in MSGOBJPI.CPP module,
extract them, hide them or do everything you want.
find_origin(char*text): this function returns a char* to the last origin of
the message pointed by text.
area: an integer with the numebr of the area you want to access.
message_number: an integer with the number of the message you want to access.
fromaddr,toaddr: addresses of the sender and the recipient of the message;
these members are object themselves. Consult MSGOBJ.H for their
description.
attributes,status: message attributes (crash, hold, kill/sent, etc...) in
bitmap form and message status (deleted, locked, sent, etc...).
See PIPBASE.H and FTS-0001 to know the meaning of every bit.
cost,times: unuseful and not used. These fields are here only because the
have a meaning in other message bases; maybe the will be used in
future.
text: this is a pointer to the memory allocated by allocate_text(), or
NULL if no space is allocated for your messages; when reading,
modifying or posting a message, in this area you'll have to place
the message text, a virtually unbounded (except for Intel 80X86
64K segment limit <G>), NUL terminated string.
textsize: dimension of the allocated buffer.
from,to,subject: strings (not char pointers!) containing the message header;
self-explanatory.
date: message date and time; it is an object; see MSGOBJ.H for its
simple structure.
previous,next: integer pointing to the previous and the next messages in the
same area with the same subject.
post(): this method takes the message contained in {from, to, subject,
fromaddr, toaddr, text} fields and inserts it into the area whose
number is placed in the area field.
modify(): it alters the current message (previously read); to modify a
message, read() it, change from, to, subject, fromaddr, toaddr, and
text[] fields, and then issue a modify()
del(): it kills current message (i.e.: message pointed by
<area,message_number> fields); you haven't to read() it before
del()eting it.
read(): it fills all message_frame fields with the message
or <area,message_number> (i.e.: to read a message, assign area and
read(0) message_number fields, and then issue a read()). If text is not
allocated, read() will fill only from, to, subject and date
fields.
read(1): exactly like read(), but you force a message re-reading (read()
will not access disk if you haven't modified the message number
since the last call of read().
allocate_text(size): allocates a message buffer of the specified size; you've
always to check if it returns -1 (no memory available); a 0 is
returned if text buffer is allocated; do not directly assegnate
message_frame::text pointer to a malloc-ed block, but use this
function, especially under MS Windows; if no size is specified
(i.e.: you call allocate_text()), BUFSIZE bytes are assumed; if
you call allocate_text() when text is already allocated, this
command will have no effect; notice that size is a long integer,
but I don't guarantee that buffers >64K will work with all string
operations (strings longer than 64 Kb are expressly prohibited on
my MS Windows Programming manuals).
deallocate_text(): it deallocates allocated text buffer; use always this
function, and never a free(message_frame::text).
isolate_seen_by(AUDIT*sb,int&ns,int maxns,AUDIT*pth,int&np,int maxnp): this
function extracts seen-byes and path from a message (removing
them from message text!); AUDIT structure is described somewhere
in haeader files; you must pass pointers to arrays of maxns
elements that will contain seen-byes and maxnp elements for path
informations; at return, ns and np will contain the number of
effectively read seen-bye and path elements.
highest_message(void): this returns the number of the last message in the
current (i.e.: the area you set with message_frame::area=xxx)
area; if area is empty it returns -1.
total_messages(void): this returns the total number of messages present in
the current area; for Pip Base it's always highest_message()+1.
message_frame(): the constructor; it's called automatically; it does not
allocate text buffer, nor position you on a particular area or
message.
~message_frame(): the destructor; usually, it's called automatically by BC++
standard exit() function: it closes open files and eventually
deallocates text.
Most pointers are huge. If you don't compile under a huge memory model,
you'll have to insert some casting when calling MessageObject.
ROYALTIES AND DISTRIBUTION
You're encouraged to distribute MessageObject without modifying it.
If you alter (improving) it, please send a modified and commented copy to the
author.
You may include MessageObject code into every program you write, and distribute
it. No royalties are due if your program is public domain; if it is shareware,
consider the idea of offering me something (a share on every registration, or
an una-tantum gift... everything you want and you think it may made me happy);
if it is a commercial ($$$) software, please contact me.
Please let me know every application you create with this tool.